Codex — OpenAI 终端 AI 编程 Agent

Codex CLI 是 OpenAI 开发的轻量级 AI 编程 Agent（Coding Agent）， 在本机终端（Terminal）中运行。它能理解自然语言指令、检查代码、修改文件、执行命令， 在不离开终端的情况下完成软件工程任务。 GitHub 105K+ Stars，开源协议 Apache-2.0，当前版本 v0.143.0。

1. 概述

Codex CLI 的核心是一个 ReAct（Reasoning + Acting）循环： 模型在"思考（生成计划）→ 行动（调用工具）→ 观察（获得结果）"之间反复， 直到完成用户交给的任务。它运行在 Harness（缰绳/驾驭）框架内—— 所有模型行为都被工具白名单、权限审批、沙箱隔离、会话状态持久化等工程约束包裹， 保证 Agent 的行为可预测、可控、可审计、可终止。

1.1 定位与产品形态

Codex 是 OpenAI 的 AI Coding Agent 产品矩阵中的一员，其产品形态覆盖多个表面（Surface）：

1.2 核心特性

• 终端内完整循环 — 交互式 TUI（codex）中探索代码、改文件、跑命令，一次会话持续跟进
• 非交互自动化 — codex exec 无界面运行，输出 JSONL，可接入脚本与 CI
• 本地代码审查 — codex review 对未提交改动 / 分支 diff / 提交做独立审查，不改动工作区
• 多 Agent 协作 — subagents 把复杂任务拆分给专用子代理并行执行
• 沙箱与审批 — macOS Seatbelt / Linux Landlock / Windows Sandbox 平台原生隔离 + 细粒度审批策略
• MCP 扩展 — 连接第三方工具（浏览器、Figma、GitHub、Sentry 等）
• 指令体系 — AGENTS.md 全局 + 项目分层指令，支持 override 与 fallback 文件名
• 多种认证 — ChatGPT 订阅（Plus/Pro/Biz/Edu/Ent）、API Key、Access Token
• 图像输入 — --image 把报错截图、架构图、设计稿加入 Prompt
• Web 搜索 — 默认 cached 模式，--search 切换实时联网

1.3 专有名词解释

1.4 平台化转向澄清（2026-08-19）

核实结论（基于仓库 git 历史与官方文档，2026-08-21）： 这次是"从可读到受支持"的转变，不是"从闭源到开源"——媒体所称 "底层 Rust 核心 codex-rs 此前属于内部实现、未完整开源"并不属实。

早已公开的部分（git 历史佐证）

8-19 前后的实质性变动

明确不开源的部分

• IDE 扩展（VS Code / Cursor / Windsurf 插件）
• Codex cloud（云端托管环境，仅基础镜像 codex-universal 开源）
• 模型访问与托管服务（走 ChatGPT 订阅 / API）

对本章的影响：本文源码级分析基于 commit 722784e936，结论不受此次公告影响； 6.2 节中标注 Experimental 的 app-server / remote-control / cloud 现已获官方文档背书，但成熟度标记维持不变（官方仍称 experimental）。

2. 行为分析（做什么）

2.1 用例图 — 用户与 Codex 的交互全景

展示四类参与者（开发人员、DevOps、管理员、外部系统）与 Codex 的能力边界。

图 1：Codex 顶层用例图

用例说明：Codex 的用例可分为"任务执行类"（改代码、修 bug、审查）、 "环境配置类"（登录、配置、权限）、"自动化类"（exec、review、MCP、CI）与"生命周期类"（resume/fork/archive）。

2.2 活动图 — 交互式会话主流程

展示一次 codex 交互式会话从启动到结束的完整活动链，含斜杠命令分支与 Web 搜索分支。

图 2：Codex 交互式 TUI 会话活动图

关键行为：用户在项目目录启动 codex，首次运行先走登录流程。 会话中可通过斜杠命令切换模型（/model）、查看状态（/status）、 调整权限（/permissions）、执行审查（/review）或创建 AGENTS.md（/init）。

2.3 序列图 — 一次 Agent 回合的完整链路

从用户提交 Prompt 到模型调用工具、观察结果、给出最终答复的端到端序列，展示沙箱与审批在链路中的位置。

图 3：Codex 一次 Agent 回合（含工具调用）的序列图

链路要点：模型生成的工具调用命令不会直接执行——先经 ExecPolicy 规则（allow/prompt/block）判断，再进沙箱（限制文件系统与网络）， 若需越界则触发审批（on-request 策略下弹给用户或自动审查代理）。 工具结果回填对话上下文，模型继续推理，直到完成或达到终止条件。

2.4 活动图 — 权限与沙箱决策流

Codex 对"模型生成的每条命令"执行的决策链：规则判断 → 沙箱边界 → 审批策略。

图 4：命令执行前的权限与沙箱决策流

决策逻辑：

• 规则层（execpolicy .rules） — 前缀匹配：allow 直接放行、prompt 触发审批、block 直接拒绝
• 沙箱层（sandbox_mode） — read-only 只读；workspace-write 工作区内可写；danger-full-access 无限制
• 审批层（approval_policy） — untrusted 非信任命令必问；on-request 越界才问；never 不问

3. 结构分析（由什么组成）

3.1 部署图 — 运行时拓扑

Codex CLI 部署在开发者本机，通过网络与 OpenAI 后端交互，并可通过 app-server 支撑远程/桌面客户端。

图 5：Codex 部署图

部署要点：

• Codex 二进制运行在开发机（macOS/Linux/Windows/WSL2），沙箱用平台原生机制
• 认证后（ChatGPT OAuth 或 API Key）通过 HTTPS 与 OpenAI 后端通信，本地无自有模型推理
• --oss 模式可选本地 OSS 模型提供商（LM Studio / Ollama）
• codex app-server --listen ws://IP:PORT 可把本机 Codex 能力暴露给远程 TUI / 桌面客户端（--remote 连接）
• MCP 服务器作为子进程（STDIO）或远程 HTTP 端点接入

3.2 组件图 — 模块组成

Codex 仓库的模块划分（monorepo）：core（核心循环）、CLI、SDK、MCP Server、app-server。

图 6：Codex 组件架构图

3.3 概念类图 — 领域模型

Codex 领域核心实体及其关系：Session（会话）、Turn（回合）、Item（消息/事件项）、Tool（工具）、AgentConfig（配置）。

图 7：Codex 核心领域概念类图

领域模型要点：

• Session（会话） — 一次持续交互的容器，含多轮 Turn；可存档/恢复/分支（resume/fork/archive）
• Turn（回合） — 一次用户输入驱动的模型处理周期，含多条 Item
• Item（项） — 会话中可持久化的单元：Agent 消息、推理、命令执行、文件改动、MCP 调用、Web 搜索、计划更新
• Tool（工具） — shell、文件读写、Web 搜索、MCP 工具等，均有 JSON Schema 与审批模式
• SandboxPolicy / ApprovalPolicy — 分别定义技术边界与"何时暂停"
• AGENTS.md 指令链 — 全局→项目根→当前目录逐层合并，作为 System Prompt 的一部分

4. 配置体系

4.1 配置层级与优先级

Codex 配置以 TOML 存储，多个来源按优先级合并（高→低）：

1. CLI flags 与 -c key=value 覆盖（最高）
2. 项目配置 .codex/config.toml（从项目根到当前目录，最近的优先；仅受信任项目加载）
3. Profile 文件 --profile name（~/.codex/name.config.toml）
4. 用户配置 ~/.codex/config.toml
5. 系统配置 /etc/codex/config.toml（Unix）
6. 内置默认值

4.2 常用配置键（~/.codex/config.toml）

# 默认模型
model = "gpt-5.6"

# 审批策略：untrusted | on-request | never
approval_policy = "on-request"

# 沙箱级别：read-only | workspace-write | danger-full-access
sandbox_mode = "workspace-write"

# Web 搜索：cached（默认）| indexed | live | disabled
web_search = "cached"

# 推理力度
model_reasoning_effort = "high"

# 沟通风格
personality = "friendly"   # friendly | pragmatic | none

# 日志目录（显式设置会额外启用明文 TUI 日志 codex-tui.log）
log_dir = "/absolute/path/to/codex-logs"

# Windows 原生沙箱
[windows]
sandbox = "elevated"

# 终端快捷键
[tui.keymap.global]
open_transcript = "ctrl-t"

# 命令环境变量过滤
[shell_environment_policy]
ignore_default_excludes = false
[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

常用 feature flags（[features] 表）：

启用方式：codex --enable feature_name，或在 [features] 下写 name = true。

4.3 AGENTS.md 指令体系

Codex 每次启动（每个会话）都会构建一条指令链注入 System Prompt。发现顺序：

1. 全局层：~/.codex/AGENTS.override.md（若存在）→ 否则 ~/.codex/AGENTS.md
2. 项目层：从项目根（通常 Git root）向下到当前目录，每层检查 AGENTS.override.md → AGENTS.md → 兜底文件名
3. 合并：从根向下拼接（空行分隔），越靠近当前目录越靠后、优先级越高

其它配置项：project_doc_fallback_filenames（自定义兜底文件名列表）、 project_doc_max_bytes（合并上限，默认 32 KiB，超限停止追加）、 CODEX_HOME（自定义 Codex 主目录）。

# 自定义兜底文件名与更大容量
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

4.4 MCP 扩展

MCP（Model Context Protocol）把外部工具与数据接入 Codex。支持 STDIO 服务器（本地子进程）与 Streamable HTTP 服务器（远程地址 + Bearer/OAuth 认证）。配置存于 ~/.codex/config.toml。

CLI 方式添加 MCP 服务器

# 添加 STDIO 服务器（Context7 开发者文档）
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 列出 / 登录 / 移除
codex mcp list
codex mcp login <server-name>      # 仅 Streamable HTTP 且支持 OAuth
codex mcp remove <server-name>

config.toml 方式（精细控制）

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

常用 MCP 服务器：OpenAI Docs MCP、Context7、Figma、Playwright、Chrome DevTools、Sentry、GitHub。

5. 实战演示操作手册

5.1 安装与登录

安装（macOS / Linux）

curl -fsSL https://chatgpt.com/codex/install.sh | sh

或包管理器：

npm install -g @openai/codex
brew install --cask codex

登录（首次运行）

codex        # 选择 "Sign in with ChatGPT"（Plus/Pro/Biz/Edu/Ent 订阅可用）

# API Key 方式
printenv OPENAI_API_KEY | codex login --with-api-key

# Access Token 方式（CI）
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

# 无浏览器环境
codex login --device-auth

# 验证登录
codex login status    # 已登录时退出码为 0

5.2 交互式会话实战

启动并探索项目

cd ~/my-project
codex    # 启动 TUI，默认 gpt-5.6-sol medium

# 直接给出首条指令
codex "Tell me about this project"

# 带截图/架构图启动
codex --image error-screenshot.png "debug this crash"

会话中常用斜杠命令

/model      # 切换模型与推理力度
/status     # 查看当前会话配置
/permissions# 打开权限选择器（含沙箱与可写根）
/init       # 创建 AGENTS.md 指令文件
/review     # 审查当前改动
/mcp        # 查看已连接的 MCP 服务器

低摩擦本地开发启动方式

codex --sandbox workspace-write --ask-for-approval on-request

推荐实践：任务开始前建立 Git checkpoint（commit），任务后再次 commit，保证可回退。

会话管理

codex resume                 # 恢复最近会话
codex resume <session-id>    # 按 ID 恢复
codex fork <session-id>      # 从历史会话分支出新会话
codex archive <session-id>   # 归档
codex delete <session-id>    # 删除
codex completion zsh > "${fpath[1]}/_codex"   # 补全脚本

5.3 非交互模式 codex exec

基本用法

# 一次性任务，最终消息输出到 stdout，进度在 stderr
codex exec "summarize the repository structure and list the top 5 risky areas"

# 生成发布说明并落盘
codex exec "generate release notes for the last 10 commits" | tee release-notes.md

# 不持久化会话文件
codex exec --ephemeral "triage this repository and suggest next steps"

管道输入（stdin）

# prompt + stdin（stdin 作为附加上下文）
npm test 2>&1 | codex exec "summarize the failing tests and propose the smallest likely fix"

# stdin 即完整 prompt（- 哨兵强制）
cat prompt.txt | codex exec -

# 动态组装 prompt
generate_prompt.sh | codex exec - --json > result.jsonl

机器可读输出

# JSONL 事件流（thread.started / turn.started / turn.completed / item.* / error）
codex exec --json "summarize the repo structure" | jq

# 只保存最终消息到文件（同时仍打印 stdout）
codex exec "Extract project metadata" --output-schema ./schema.json -o ./project-metadata.json

自动化安全设置

# 允许工作区内编辑
codex exec --sandbox workspace-write "<task>"

# 只读默认（read-only）；危险场景才用 danger-full-access
codex exec "<task>"

# 忽略用户配置 / 忽略 rules 文件（受控环境）
codex exec --ignore-user-config --ignore-rules "<task>"

# 非 Git 目录运行（默认要求 Git 仓库以防破坏）
codex exec --skip-git-repo-check "<task>"

恢复非交互会话

codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
codex exec resume <SESSION_ID>

认证注入（CI 单次运行）

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

5.4 codex review 代码审查

# 审查未提交改动（staged + unstaged + untracked）
codex review --uncommitted

# 对比基线分支（PR 风格）
codex review --base main

# 审查某次提交
codex review --commit <SHA>

# 自定义审查指令
codex review "focus on the auth refactor, flag security issues"

--uncommitted、--base、--commit 与自定义 PROMPT 互斥；--title 仅配合 --commit。 审查不会修改工作区，只输出按优先级排序的问题。

5.5 CI 自动化实战

GitHub Actions：CI 失败自动修复（核心模式）

# 1. 主 CI 失败时触发 follow-up workflow
# 2. 以只读权限 checkout 失败 commit
# 3. 用 openai/codex-action 跑 Codex（保护 API key）
# 4. 把改动序列化为 patch artifact
# 5. 独立 job 应用 patch 并开 PR（该 job 无 API key 权限）

name: Codex auto-fix on CI failure
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
jobs:
  generate_fix:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: |
          if [ -f package-lock.json ]; then npm ci; fi
      - name: Run Codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: |
            The CI workflow "${{ github.event.workflow_run.name }}" failed for
            commit ${{ github.event.workflow_run.head_sha }}. Run `npm test --silent`
            to reproduce. Implement only the minimal fix, run tests again. Do not
            refactor unrelated files.
      - name: Create patch artifact
        id: diff
        run: |
          git add -N .
          git diff --binary HEAD > codex.patch
          if [ -s codex.patch ]; then echo "has_patch=true" >> "$GITHUB_OUTPUT"; else echo "has_patch=false" >> "$GITHUB_OUTPUT"; fi
      - name: Upload patch artifact
        if: steps.diff.outputs.has_patch == 'true'
        uses: actions/upload-artifact@v4
        with:
          name: codex-fix-patch
          path: codex.patch
          if-no-files-found: error
  open_pr:
    needs: generate_fix
    if: needs.generate_fix.outputs.has_patch == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
      - uses: actions/download-artifact@v4
        with:
          name: codex-fix-patch
      - name: Apply Codex patch
        run: git apply --index codex.patch
      - name: Open pull request
        env:
          GH_TOKEN: ${{ github.token }}
          RUN_ID: ${{ github.event.workflow_run.run_id }}
        run: |
          branch="codex/auto-fix-$RUN_ID"
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git commit -m "Auto-fix failing CI via Codex"
          git push origin "$branch"
          gh pr create --base "${{ github.event.workflow_run.head_branch }}" \
            --head "$branch" --title "Auto-fix failing CI via Codex" \
            --body-file pr-body.md

完整安全清单参见 codex-action 安全文档。

6. 参数指令速查手册

6.1 全局 flags（适用于 codex / exec / resume 等）

6.2 子命令速查

6.3 codex exec 全部 flags

6.4 斜杠命令速查（交互式 TUI 内）

6.5 沙箱与审批模式速查

审批审查者：approvals_reviewer = "user"（默认，弹给用户）或 "auto_review"（交给审查子代理自动审）。

平台沙箱实现：macOS Seatbelt（开箱即用）；Linux/WSL2 用 bubblewrap（sudo apt install bubblewrap）； Windows 用原生 Windows Sandbox（PowerShell）或 Linux 沙箱（WSL2）。

权限 Profile：内置 :read-only、:workspace、:danger-full-access； 自定义用 [permissions.<name>] 表 + default_permissions。 codex sandbox --permission-profile <NAME> -- <command> 可在沙箱中手动跑命令。

6.6 模型速查

推理力度：Low/Medium/High/Extra High（CLI 里 /model 调）。 Max = 单一任务更多思考时间；Ultra = 用 subagents 并行拆分复杂任务。 切换：codex --model gpt-5.6 或 codex exec -m gpt-5.6 "..."。

7. Agent System Prompt 梳理（源码级）

7.1 三层架构总览

Codex 的最终请求体由三层内容拼装而成，分别承担"你是谁"、"当前环境如何"、"会话历史是什么"：

图 8：Codex Prompt 三层组装架构

角色分工：Responses API 中基础指令放在 instructions 字段（或 responses-lite 模式下作为前缀 developer 消息）， WorldState 与历史以 developer / user 角色的 ResponseItem 流式注入，保持增量可缓存。

7.2 基础指令（instructions_template）

与 OpenCode 在代码里硬编码各模型 .txt 不同，Codex 的 System Prompt 主体由 模型目录（model catalog）下发——每个模型在目录里声明自己的 model_messages.instructions_template。本地 models-manager/models.json 是 兜底目录（离线可用），真实运行时会从 OpenAI 拉取最新目录并缓存。

模型目录中的 instructions_template 长度对比

解析逻辑（protocol/src/openai_models.rs:487-505 ModelInfo::get_model_instructions）： 若 instructions_variables 存在，则把模板中的 {{ personality }} 占位符 替换为当前人格消息（friendly/pragmatic/默认）；若模板无占位符则视为纯文本直接返回。

gpt-5.6-sol 基础指令的章节结构（原文节选）

本地兜底与旧模型模板

本地兜底 models-manager/prompt.md（也是 gpt-5.2-codex 的 fallback）是最详尽的一版， 含 # AGENTS.md spec（作用域/优先级/嵌套覆盖）、## Responsiveness（preamble 消息规范与示例）、 ## Planning（update_plan 高质量/低质量计划示例）、## Task execution （"keep going until the query is completely resolved"）、## Ambition vs. precision、 # Tool Guidelines（apply_patch 完整文法）。这正是模型能力尚弱时需要"喂更多规则"的体现—— 模板越长 = 模型越弱，GPT-5.6 靠更强的原生能力压缩了提示词篇幅。

7.3 WorldState 模块化上下文系统

WorldState（core/src/context/world_state/mod.rs）是 Codex 的核心提示词机制： 把动态上下文拆成多个独立的 WorldStateSection，每个 section 负责渲染一段"模型可见状态"。 它实现了 AGENTS.md 里要求的全部上下文工程约束： 无历史重写、避免缓存失效、所有注入有界、单条 ≤10K token、所有碎片实现统一 trait。

图 9：WorldState 各 section 及其注入角色

section 清单（build_world_state_for_step 顺序）

diff 渲染机制

每个 section 的 snapshot() 产出结构化快照，render_diff(previous) 只输出 相对上次变化的部分。持久化到 rollout 的快照经 RFC 7386 merge-patch 计算差异； 模型可见的碎片用 SHA-1 哈希（WorldStateHash）去重。效果：

• 首回合（Absent→Current）：所有 section 全量渲染
• 稳态回合（Known→Current）：未变化的 section 返回 None，不重复注入 → 大幅降低 token 与缓存 miss
• 历史保留：通过 marker（如 <environment_context>）在历史中识别已注入碎片，支持 Unknown 状态回退

7.4 请求组装流程

从用户输入到 Responses API 请求体的完整链路（core/src/session/turn.rs + core/src/client.rs）：

图 10：Codex 请求组装流程（run_turn → build_responses_api_request）

组装要点：

1. run_turn 每次采样前：capture_step_context 捕获环境/工具/MCP → record_step_world_state_if_changed 计算 WorldState diff → clone_history().for_prompt() 规范化历史
2. build_responses_api_request（client.rs:850-944）决定请求形态：
   • responses-lite 模式（gpt-5.6 系列 use_responses_lite=true）：基础指令作为前缀 developer 消息 + AdditionalTools 注入 input 头部，instructions 字段留空
   • 普通模式：基础指令放 instructions 字段，工具放 tools 字段
3. 请求参数：tool_choice: "auto"、parallel_tool_calls（按模型能力）、reasoning（effort + summary）、stream: true、include: ["reasoning.encrypted_content"]
4. 非 OpenAI 提供商：剥离加密参数与内部 metadata

7.5 ReAct 循环与终止条件（run_turn）

Codex 的循环不是靠 Prompt 措辞驱动（对比 OpenCode 的 beast.txt"必须循环到底"）， 而是纯代码层 while 循环（core/src/session/turn.rs:282-569 run_turn）。 循环条件由 end_turn 标志与 token 预算共同决定：

图 11：run_turn 主循环（含自动压缩与终止判定）

循环终止判定（run_turn 内）：

关键点：Codex 通过 ResponseEvent::Completed{ end_turn } 判断是否继续—— 工具调用被模型"发出"后，若后端判定需要 follow-up 则循环继续；这与 "模型自主决定何时结束"的 OpenCode 模型不同，Codex 把循环控制权交给响应事件，更可控。

7.6 工具 schema 速查

工具集在 core/src/tools/spec_plan.rs:891 add_core_tool_sources 组装，按 feature flags 动态增减：

guardian 特例：审查者子代理（guardian reviewer）只拿到 exec_command / write_stdin / view_image，通用工具全部排除 （spec_plan.rs:894-922）。

7.7 AGENTS.md 注入机制

AGENTS.md 作为 user 角色碎片注入，带 marker # AGENTS.md instructions / </INSTRUCTIONS>（context/user_instructions.rs）：

# AGENTS.md instructions for {directory}

<INSTRUCTIONS>
{AGENTS.md 合并文本}

注入逻辑（world_state/agents_md.rs）：

• 首次注入：直接渲染合并文本
• 替换：前置 "These AGENTS.md instructions replace all previously provided AGENTS.md instructions."
• 移除：注入 "The previously provided AGENTS.md instructions no longer apply."

加载优先级见 4.3 节（全局 override → 项目根向下逐层，越近越优先）。 合并上限 project_doc_max_bytes 默认 32 KiB；达到后停止追加，避免无限膨胀。

7.8 权限与沙箱指令注入

PermissionsInstructions（prompts/src/permissions_instructions.rs）把 沙箱模式、审批策略、execpolicy 规则组装成一段 developer 指令。模板均为 .md 文件，支持 {{ network_access }} 占位符：

# workspace-write 沙箱注入文本
Filesystem sandboxing defines which files can be read or written. `sandbox_mode` is
`workspace-write`: The sandbox permits reading files, and editing files in `cwd` and
`writable_roots`. Editing files in other directories requires approval. Network access
is {{ network_access }}.

on-request 审批策略注入要点（approval_policy/on_request.md）：

• 命令按 shell 控制运算符（|、&&、;、$()）切成段逐段评估
• 需越权时用 sandbox_permissions="require_escalated" + justification 参数请求审批
• prefix_rule 建议被禁止宽泛（如 python3）、禁止用于破坏性命令（rm）与 heredoc

execpolicy .rules 文件格式（Starlark 语法）：

# 允许 git status（含 match 单元测试）
prefix_rule(
    pattern = ["git", "status"],
    decision = "allow",
    justification = "git status is read-only",
    match = [["git", "status"], "git status"],
    not_match = [["git", "reset"]],
)
# 阻断并给替代建议
prefix_rule(pattern = ["git", "merge"], decision = "forbidden",
            justification = "Use rebase instead.")

决策：allow / prompt / forbidden，多规则命中取最严（forbidden > prompt > allow）。

7.9 Personality 人格系统

人格不是单独一段指令，而是烘焙进基础指令模板：模板含 {{ personality }} 占位符， ModelInstructionsVariables 提供 default / friendly / pragmatic 三套人格文本 （models-manager/src/model_info.rs）：

处理细节（model_info.rs with_config_overrides）：personality 禁用时把占位符替换为 default 并清除变量； personality=None 时用 strip_personality_section 删除整个 # Personality 章节。

7.10 Compaction 与 Review 专用 Prompt

上下文压缩（compaction）

上下文超限时，Codex 用专门的压缩提示词让模型产出交接摘要（prompts/templates/compact/prompt.md）：

You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for
another LLM that will resume the task.

Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue

Be concise, structured, and focused on helping the next LLM seamlessly continue the work.

压缩后基础指令（instructions）会被保留为 developer 消息，保证"换脑不换身"。

代码审查（review rubric）

codex review 使用独立系统提示词 prompts/templates/review/rubric.md，核心规则：

• 按 8 条通用判定标准识别 bug（影响正确性/性能/安全/可维护性、离散可行动、非既有 bug、作者会修等）
• 评论规范：一段以内、代码片段 ≤3 行、客观语气、不奉承
• 优先级 P0-P3 标签 + JSON 输出 priority 字段（0/1/2/3）
• 每条 finding 附仓库规则（AGENTS.md）引用；结束输出整体正确性裁决

7.11 实战 Case 演示：一次完整会话的请求体组装

下面用一个虚构但完全符合源码逻辑的场景，走一遍从"用户输入"到"Responses API 请求体"的完整组装， 再对比首回合（全量注入）与稳态回合（仅 diff）的差异，直观理解 WorldState 的 token 节省效果。

场景设定

Case 1 — 首回合请求体（全量注入）

build_responses_api_request（client.rs:850）在 responses-lite 模式下： input 数组头部 = AdditionalTools（developer）→ base_instructions（developer）→ WorldState 各 section（developer/user）→ 最终用户消息。请求体示意（为可读性做了裁剪，真实内容更长）：

POST /v1/responses   (Responses API, stream=true)
{
  "model": "gpt-5.6-sol",
  "instructions": "",                        // responses-lite 模式置空
  "input": [
    // ── L1 基础指令（作为前缀 developer 消息）──
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "You are Codex, an agent based on GPT-5. You and the user share one
                 workspace... # Personality(烘焙 friendly) ... # Working with the user
                 ... # Rules for getting work done ... # Destructive Actions
                 ... # Using skills"          // 约 17.7K 字符
      }]
    },
    // ── L2 WorldState：模型切换 → 空（首回合无 previous_model）──
    // ── L2 WorldState：人格 → 已烘焙进基础指令，不重复注入 ──
    // ── L2 WorldState：权限与沙箱（developer）──
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "Filesystem sandboxing defines which files can be read or written.
                 `sandbox_mode` is `workspace-write`: The sandbox permits reading
                 files, and editing files in `cwd` and `writable_roots`. Editing
                 files in other directories requires approval. Network access is
                 allowed for configured domains.\n\n# Escalation Requests\n
                 Commands are run outside the sandbox if they are approved...\n\n
                 ## How to request escalation\nIMPORTANT: To request approval...
                 `sandbox_permissions` with `\"require_escalated\"`..."
      }]
    },
    // ── L2 WorldState：协作模式（developer）──
    {
      "role": "developer",
      "content": [{
        "type": "input_text",
        "text": "..."
      }]
    },
    // ── L2 WorldState：环境上下文（user，XML 结构）──
    {
      "role": "user",
      "content": [{
        "type": "input_text",
        "text": "\n  /Users/brian/my-app\n
                 zsh\n  2026-08-11\n
                 Asia/Shanghai\n
                 /Users/brian/my-app
                 ...
                 \n"
      }]
    },
    // ── L2 WorldState：AGENTS.md（user）──
    {
      "role": "user",
      "content": [{
        "type": "input_text",
        "text": "# AGENTS.md instructions for /Users/brian/my-app\n\n
                 \n- 修改 JS 后必须跑 npm test\n- 用 pnpm 安装依赖\n
                 - 新增生产依赖前先确认\n"
      }]
    },
    // ── L3 用户消息 ──
    {
      "role": "user",
      "content": [{
        "type": "input_text",
        "text": "看一下项目结构，然后帮我把 README 补全"
      }]
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": false,
  "reasoning": { "effort": "medium" },
  "stream": true,
  "include": ["reasoning.encrypted_content"]
}

注意：AdditionalTools（exec_command / write_stdin / apply_patch / update_plan / spawn_agent 等工具 schema）作为独立 developer item 放在 input 最前，此处省略。 工具定义走 tool_choice=auto，由模型按需调用。

Case 2 — 一次工具调用回合（模型 → 沙箱 → 审批）

模型收到首回合请求后，推理出需要先探索项目结构，发出工具调用：

// 模型输出的 FunctionCall item
{
  "type": "function_call",
  "call_id": "call_ab12",
  "name": "exec_command",
  "arguments": {
    "cmd": "ls -la && cat package.json",
    "workdir": "/Users/brian/my-app"
  }
}

Codex 收到该调用后，走 execpolicy → 沙箱 → 审批 决策链（见 2.4 节活动图）：

若模型尝试 越界写（如 npm install 需要写 node_modules 之外或下载依赖触发网络规则）， 沙箱会拒绝并要求 require_escalated，此时触发审批（on-request）弹给用户：

// 模型感知需越权，重发请求
{
  "type": "function_call",
  "call_id": "call_cd34",
  "name": "exec_command",
  "arguments": {
    "cmd": "npm install",
    "sandbox_permissions": "require_escalated",
    "justification": "需要安装项目依赖（下载 npm 包），允许吗？",
    "prefix_rule": ["npm", "install"]     // 可选，用户批准后可持久化
  }
}

Case 3 — 稳态回合：WorldState 只发 diff

用户追问一句"顺便告诉我 node 版本要求"，此时进入第 2 个采样请求。WorldState 的 render_diff 对比持久化快照，未变化的 section 返回 None 不重复注入：

稳态请求体示意：

{
  "model": "gpt-5.6-sol",
  "instructions": "",
  "input": [
    // L1 基础指令在历史中已存在（responses-lite 前缀，由缓存命中）
    // 不重复注入
    {
      "role": "user",
      "content": [{ "type": "input_text",
                    "text": "ls 结果 + package.json 内容（上一轮工具输出）" }]
    },
    {
      "role": "assistant",
      "content": [{ "type": "output_text",
                    "text": "项目结构已看完，根目录有 src/、tests/、package.json。接下来补全 README。" }]
    },
    {
      "role": "user",
      "content": [{ "type": "input_text", "text": "顺便告诉我 node 版本要求" }]
    }
  ]
}

效果：稳态回合不再重复注入 ~17.7K 字符的基础指令 + 权限/环境/AGENTS.md 等 WorldState 碎片， 只发送新增的历史消息。配合 Responses API 的 prompt caching（缓存键见 prompt_cache_key）， 重复前缀直接命中缓存，token 成本大幅下降。

Case 4 — 上下文超限自动压缩（compaction）

当历史 + 前缀接近模型上下文窗口（gpt-5.6-sol 为 272K，auto-compact 默认取 90% ≈ 244.8K）， run_turn 触发 run_auto_compact：

1. 把压缩提示词（7.10 节的 compact/prompt.md）发给模型，让它产出交接摘要
2. 基础指令（L1）作为 developer 前缀保留；WorldState 用 replace_compacted_history 重建
3. 历史被替换为：压缩摘要 + 最近未压缩消息，模型在提示词中被明确告知"你在一次压缩后的会话中，不要重启"

// 压缩后首条历史消息
{
  "role": "developer",
  "content": [{ "type": "input_text",
                "text": "## 项目结构 ##\n- src/ (入口 main.ts, 路由 /api)\n
                         ## 已完成 ##\n- 浏览了项目结构，确认使用 Node 18+\n
                         ## 下一步 ##\n- 补全 README（引用实际命令与结构）\n
                         ## 关键约束 ##\n- AGENTS.md: 改 JS 后跑 npm test" }]
}

压缩后模型继续处理，提示词明确"上下文被自动压缩过，不要从头开始，继续未完成工作"。